---
title: "Breadcrumbs"
description: "Breadcrumbs display a hierarchy of links to the current page or resource in an application."
---

import {breadcrumbsContent} from "@/content/components/breadcrumbs";

# Breadcrumbs

Breadcrumbs display a hierarchy of links to the current page or resource in an application.

<ComponentLinks component="breadcrumbs" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add breadcrumbs",
    npm: "npm install @heroui/breadcrumbs",
    yarn: "yarn add @heroui/breadcrumbs",
    pnpm: "pnpm add @heroui/breadcrumbs",
    bun: "bun add @heroui/breadcrumbs"
  }}
/>


## Import

HeroUI exports 2 breadcrumb-related components:

- **Breadcumbs**: The main component, which is a wrapper for the other components.
- **BreadcrumbItem**: The component that represents a breadcrumb item.

<ImportTabs
  commands={{
    main: 'import {Breadcrumbs, BreadcrumbItem} from "@heroui/react";',
    individual: 'import {Breadcrumbs, BreadcrumbItem} from "@heroui/breadcrumbs";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={breadcrumbsContent.usage} />

### Disabled

Disabled breadcrumbs display items but prevent navigation, ensuring a consistent layout. The last item, signifying the current page, isn't disabled.

<CodeDemo title="Disabled" files={breadcrumbsContent.disabled} />

### Sizes

<CodeDemo title="Sizes" files={breadcrumbsContent.sizes} />

### Colors

<CodeDemo title="Colors" files={breadcrumbsContent.colors} />

### Variants

<CodeDemo title="Variants" files={breadcrumbsContent.variants} />

### Underlines

<CodeDemo title="Underlines" files={breadcrumbsContent.underlines} />

### Radius

<CodeDemo title="Radius" files={breadcrumbsContent.radius} />

### Routing

The `<BreadcrumbItem>` component works with frameworks and client side routers like [Next.js](https://nextjs.org/) and
[React Router](https://reactrouter.com/en/main). See the [Routing](/docs/guide/routing) guide to learn how to set this up.

<CodeDemo title="Routing" files={breadcrumbsContent.routing} />

### Controlled

You can control the current/active item by using the `isCurrent` and `onAction` props.

<CodeDemo title="Controlled" files={breadcrumbsContent.controlled} />

> **Note**: If needed you can use the `onPress` prop to handle the click event on the breadcrumb item.

### Menu Type

It is possible to use the `Breadcrumbs` component as a horizontal menu. This is useful when you want to display a list
of possible navigations and let the user choose one of them.

<CodeDemo title="Menu Type" files={breadcrumbsContent.menuType} />

### Start & End Content

You can add any element to the start or end of the breadcrumbs by using the `startContent` and `endContent` props. The
above example uses the `startContent` prop to add icons to the start of the breadcrumbs.

<CodeDemo title="Start & End Content" files={breadcrumbsContent.startEndContent} />

### Custom Separator

You can customize the separator between breadcrumbs by using the `separator` prop.

<CodeDemo title="Separator" files={breadcrumbsContent.separator} />

### Custom Items

the `BreadcrumbItem` component accepts any element as its children. This allows you to customize the appearance of the
breadcrumb items.

The above example uses the [Dropdown](/docs/components/dropdown) component to create a dropdown menu in the breadcrumb.

<CodeDemo title="Custom Items" files={breadcrumbsContent.customItems} />

The `Breadcrumbs` component picks only the `BreadcrumbItem` components as its children. This means that you cannot
place any other component directly inside the `Breadcrumbs` component.

```tsx
// ❌ This will not work,
// The Button will not be picked by the Breadcrumbs component.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <Button>Item 2</Button>
</Breadcrumbs>

// ✅ Instead, you can wrap the Button inside a BreadcrumbItem.
<Breadcrumbs>
  <BreadcrumbItem>Item 1</BreadcrumbItem>
  <BreadcrumbItem>
    <Button>Item 2</Button>
  </BreadcrumbItem>
</Breadcrumbs>
```

### Collapsing Items

The `Breadcrumb` component provides 3 props to control the collapsing of items:

- `maxItems`: Specifies the maximum number of breadcrumbs to display. When there are more
  than the maximum number, only the first `itemsBeforeCollapse` and last `itemsAfterCollapse`
  will be shown, with an ellipsis in between.
- `itemsBeforeCollapse`: If max items is exceeded, the number of items to show before the ellipsis.
- `itemsAfterCollapse`: If max items is exceeded, the number of items to show after the ellipsis.

<CodeDemo title="Collapsing Items" files={breadcrumbsContent.collapsingItems} />

> **Note**: The ellipsis item will use the first collapsed item as its `href` prop.

### Customizing the Ellipsis Item

You can customize the ellipsis item by using the `renderEllipsis` prop. This prop accepts a function that returns a
React element.

<CodeDemo title="Customizing the Ellipsis Item" files={breadcrumbsContent.customizingEllipsis} />

## Slots

- Breadcrumbs Slots

- **base**: The main slot for the breadcrumbs. It wraps the `list` slot.
- **list**: The list of breadcrumbs wrapper.
- **ellipsis**: The slot for the ellipsis item. This is only visible when the breadcrumbs are collapsed.
- **separator**: The slot for the custom separator, the one that can be set using the `separator` prop.

- BreadcrumbItem Slots

- **base**: The main slot for the breadcrumb item. It wraps the `item` slot.
- **item**: The breadcrumb item wrapper.
- **separator**: The slot for the item separator.

### Customizing the Breadcrumbs Styles

You can customize the `Breadcrumbs` style by using the `classNames` prop and its items by using the `itemClasses` prop.

<CodeDemo title="Custom Breadcrumbs Styles" files={breadcrumbsContent.customStyles} />

<Spacer y={4} />

## Data Attributes

`BreadcrumbItem` has the following attributes on the `item` element:

- **data-current**:
  When the breadcrumb item is the current item. Based on breadcrumb `isCurrent` prop or on whether the item is the last one.
- **data-disabled**:
  When the breadcrumb item is disabled. Based on breadcrumb `isDisabled` prop.
- **data-focus**:
  When the breadcrumb item is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-focus-visible**:
  When the breadcrumb item is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).

<Spacer y={4} />

## Accessibility

- Implemented as an ordered list of items.
- Support for mouse, touch, and keyboard interactions on breadcrumbs.
- Support for navigation links via `<a>` elements or custom element types via ARIA.
- Localized ARIA labeling support for landmark navigation region.
- Support for disabled breadcrumbs.
- The last item is automatically marked as the current page using `aria-current`.

<Spacer y={4} />

## API

### Breadcrumbs Props

<APITable
  data={[
    {
      attribute: "children*",
      type: "ReactNode",
      description: "The contents of the Breadcrumbs. Usually a list of `BreadcrumbItem` components.",
      default: "-"
    },
    {
      attribute: "variant",
      type: "solid | bordered | light",
      description: "The Breadcrumbs list appearance style.",
      default: "solid"
    },
    {
      attribute: "color",
      type: "foreground | primary | secondary | success | warning | danger",
      description: "The Breadcrumbs' items color theme.",
      default: "foreground"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The Breadcrumbs' items size.",
      default: "md"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The Breadcrumbs list border radius.",
      default: "-"
    },
    {
      attribute: "underline",
      type: "none | active | hover | focus | always",
      description: "The Breadcrumbs' items underline style.",
      default: "none"
    },
    {
      attribute: "separator",
      type: "ReactNode",
      description: "The custom separator between Breadcrumbs. It is a chevron by default.",
      default: "-"
    },
    {
      attribute: "maxItems",
      type: "number",
      description: "The maximum number of breadcrumbs to display.",
      default: "-"
    },
    {
      attribute: "itemsBeforeCollapse",
      type: "number",
      description: "The number of items to show before the ellipsis.",
      default: "-"
    },
    {
      attribute: "itemsAfterCollapse",
      type: "number",
      description: "The number of items to show after the ellipsis.",
      default: "-"
    },
    {
      attribute: "hideSeparator",
      type: "boolean",
      description: "Whether to hide the separator between breadcrumbs.",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the Breadcrumbs are disabled except the last item.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the Breadcrumbs should display animations.",
      default: "false"
    },
    {
      attribute: "itemClasses",
      type: "Partial<Record<\"base\" | \"item\" | \"separator\", string>>",
      description: "Allows to set custom class names for the breadcrumbs item slots.",
      default: "-"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"list\" | \"ellipsis\" | \"separator\", string>>",
      description: "Allows to set custom class names for the breadcrumbs slots.",
      default: "-"
    }
  ]}
/>

### Breadcrumbs Events

<APITable
  data={[
    {
      attribute: "onAction",
      type: "(key: React.Key) => void",
      description: "Handler called when any breadcrumb item is pressed. It returns the item key.",
      default: "-"
    }
  ]}
/>

### BreadcrumbItem Props

<APITable
  data={[
    {
      attribute: "children*",
      type: "ReactNode",
      description: "The contents of the item. Usually the link label or icon.",
      default: "-"
    },
    {
      attribute: "color",
      type: "foreground | primary | secondary | success | warning | danger",
      description: "The item color theme.",
      default: "foreground"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The item size.",
      default: "md"
    },
    {
      attribute: "underline",
      type: "none | active | hover | focus | always",
      description: "The item underline style.",
      default: "none"
    },
    {
      attribute: "startContent",
      type: "ReactNode",
      description: "The item start content.",
      default: "-"
    },
    {
      attribute: "endContent",
      type: "ReactNode",
      description: "The item end content.",
      default: "-"
    },
    {
      attribute: "separator",
      type: "ReactNode",
      description: "The item custom separator. It is a chevron by default.",
      default: "-"
    },
    {
      attribute: "isCurrent",
      type: "boolean",
      description: "Whether the item is the current/active one.",
      default: "false"
    },
    {
      attribute: "isLast",
      type: "boolean",
      description: "Whether the item is the last one.",
      default: "false"
    },
    {
      attribute: "hideSeparator",
      type: "boolean",
      description: "Whether to hide the item separator.",
      default: "false"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the item is disabled.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the item should display animations.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\" | \"item\" | \"separator\", string>>",
      description: "Allows to set custom class names for the item slots.",
      default: "-"
    }
  ]}
/>

### BreadcrumbItem Events

<APITable
  data={[
    {
      attribute: "onPress",
      type: "(e: PressEvent) => void",
      description: "Handler called when the press is released over the target.",
      default: "-"
    },
    {
      attribute: "onPressStart",
      type: "(e: PressEvent) => void",
      description: "Handler called when a press interaction starts.",
      default: "-"
    },
    {
      attribute: "onPressEnd",
      type: "(e: PressEvent) => void",
      description: "Handler called when a press interaction ends, either over the target or when the pointer leaves the target.",
      default: "-"
    },
    {
      attribute: "onKeyDown",
      type: "(e: KeyboardEvent) => void",
      description: "Handler called when a key is pressed.",
      default: "-"
    },
    {
      attribute: "onKeyUp",
      type: "(e: KeyboardEvent) => void",
      description: "Handler called when a key is released.",
      default: "-"
    }
  ]}
/>

<Spacer y={2} />

### Types

#### Render Ellipsis Function

```ts
export type RenderEllipsisItemProps = {
  /**
   * The collapsed items.
   */
  items: BreadcrumbItemProps[];
  /**
   * The max number of items.
   */
  maxItems: number;
  /**
   * The picked item to render the ellipsis.
   */
  collapsedItem: ReactNode;
  /**
   * The default ellipsis icon.
   */
  ellipsisIcon: ReactNode;
  /**
   * Number of items to show before the ellipsis.
   */
  itemsBeforeCollapse: number;
  /**
   * Number of items to show after the ellipsis.
   */
  itemsAfterCollapse: number;
  /**
   * The separator between each breadcrumb. It is a chevron by default.
   */
  separator: ReactNode;
};

renderEllipsis: (props: RenderEllipsisItemProps) => ReactNode;
```
